---
title: Get Started
hide_title: true
---

# Get Started with the Terraform Controller

## Preflight Checks

To set up the TF-controller, you will need to follow the steps in the preflight checks.
Here is a summary of what you will need to do:

  1. Install Flux **v0.32.0** or later on your cluster. This includes installing the Flux CLI on your local machine and installing the Flux controllers on the cluster.
  2. Configure the network firewall or security groups on your cluster to allow incoming connections to **port 30000** on **each Runner's Pod in each namespace**.
     This will allow the Controller to communicate with the Runner's Pod via gRPC.
  3. Configure the network firewall or security groups on your cluster to allow the Controller to download tar.gz BLOBs **from the Source controller** via **port 80** and
     to post events to **the Notification controller** via **port 80**.

It is important to note that the exact steps for setting up the TF-controller will depend on the specific environment
and infrastructure that you are using. You may need to refer to the documentation for your specific environment or
infrastructure to get more detailed instructions on how to set this up.

## GitOps Installation

To set up TF-Controller, you will need to perform the following actions:

1. Create a local cluster using a tool such as `kind` or `minikube`. This will allow you to develop and test the Terraform Controller in a local environment before deploying it to a production cluster.
   ```bash
   kind create cluster --name tf-controller
   ```

2. Install the Flux CLI on your local machine. This will allow you to interact with the Flux controllers on your cluster.
   ```bash
   brew install fluxcd/tap/flux
   ```

3. Prepare a git repository to store the configuration files and manifests for Flux and TF-controller. Assuming you have a GitHub account, and your username is `$GITHUB_USER`, you can create a new repository called `gitops-tf-controller` using the following command:
   ```bash
   export GITHUB_USER=<your github username>
   export GITHUB_TOKEN=<your github personal access token>

   gh repo create $GITHUB_USER/gitops-tf-controller
   ```

4. Bootstrap the cluster with Flux v2 (v0.32.0 or later) using the path for example `./cluster/my-cluster`. This will install Flux on the cluster and create a Flux system at `./cluster/my-cluster/flux-system`.
   ```bash
   git clone git@github.com:$GITHUB_USER/gitops-tf-controller.git
   cd gitops-tf-controller

   flux bootstrap github \
     --owner=$GITHUB_USER \
     --repository=gitops-tf-controller \
     --branch=main \
      --path=./cluster/my-cluster \
      --personal \
      --token-auth
    ```

5. Create a directory at `./cluster/my-cluster/infra/` and place the file `tf-controller.yaml` in this directory.
   Download the TF-controller manifest from the release location (https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml)
    and saving it to `./cluster/my-cluster/infra/tf-controller.yaml`. Add the manifest file to the git repository, commit the changes, and push the repository.
    ```bash
    mkdir -p ./cluster/my-cluster/infra/
    curl -s https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml > ./cluster/my-cluster/infra/tf-controller.yaml
    ```

6. In the same directory, create `kustomization.yaml` file that contains the following:
    ```yaml
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    resources:
      - tf-controller.yaml
    ```
    Add the `kustomization.yaml` file to the git repository, commit the changes, and push the repository.

If you want to use the Terraform Controller with the Notification Controller,
you will also need to modify the manifest to allow the Notification Controller to work with the Terraform Controller.
The exact steps for doing this will depend on the specific requirements of your environment and the configuration of the Notification Controller.
You may need to refer to [the documentation for the Terraform Controller and Notification Controller](https://fluxcd.io/flux/cheatsheets/bootstrap/#enable-notifications-for-third-party-controllers)
for more information on how to set this up.

## Other Installation Methods

Before using TF-controller, you have to install Flux by using either `flux install` or `flux bootstrap` command.
Please note that TF-controller now requires **Flux v0.32.0** or later, so please make sure you have the latest version of Flux.
After that you can install TF-controller with Flux HelmRelease by:

```shell
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml
```

For the most recent release candidate of TF-controller, please use [rc.yaml](https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml).

```shell
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml
```

or manually with Helm by:

```shell
# Add tf-controller helm repository
helm repo add tf-controller https://weaveworks.github.io/tf-controller/

# Install tf-controller
helm upgrade -i tf-controller tf-controller/tf-controller \
    --namespace flux-system
```

For details on configurable parameters of the TF-controller chart,
please see [chart readme](https://github.com/weaveworks/tf-controller/tree/main/charts/tf-controller#tf-controller-for-flux).

Alternatively, you can install TF-controller via `kubectl`:

```shell
export TF_CON_VER=v0.13.1
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml
```

## Quick start

Here's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.

### Define source

First, we need to define a Source controller's source (`GitRepository`, `Bucket`, `OCIRepository`), for example:

```yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: helloworld
  namespace: flux-system
spec:
  interval: 30s
  url: https://github.com/tf-controller/helloworld
  ref:
    branch: main
```

### The GitOps Automation mode

The GitOps automation mode could be enabled by setting `.spec.approvePlan=auto`. In this mode, Terraform resources will be planned,
and automatically applied for you.

```yaml
apiVersion: infra.contrib.fluxcd.io/v1alpha1
kind: Terraform
metadata:
  name: helloworld
  namespace: flux-system
spec:
  interval: 1m
  approvePlan: auto
  path: ./
  sourceRef:
    kind: GitRepository
    name: helloworld
    namespace: flux-system
```

For a full list of features and how to use them, please follow the [terraform section](../overview) in our docs.

## Other Examples
  * A Terraform GitOps with Flux to automatically reconcile your [AWS IAM Policies](https://github.com/tf-controller/aws-iam-policies).
  * GitOps an existing EKS cluster, by partially import its nodegroup and manage it with TF-controller: [An EKS scaling example](https://github.com/tf-controller/eks-scaling).
